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EGL EXTERNAL PLATFORM API 


MOTIVATION 


Decouple platform drivers from EGL drivers such that anyone writing a new window 
system can add a platform driver to integrate with existing EGL hardware drivers. 


No vendor agreement required to support not-well-established window systems. 


Platform code can be open source even if EGL drivers are not (less closed source is 
a win). 


One common platform implementation improves consistency. 
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OVERVIEW 


Specification of an API for writing EGL platforms and their interactions with modern 
window systems. 


External platforms use application-facing EGL functions... 


.. leveraging config selection, context creation, and rendering support from lower- 
level EGL platform implementations (e.g. GBM, EGLDevice), ... 


Or even other external platforms (e.g. X11, Wayland, Android). 
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STRUCTURE 


EGL implementation > EGL external platform APIs: 
Pure EGL hooks 
Derivatives of EGL functions 
External object validation functions 
Handle translation 

EGL external platform > EGL implementation APIs: 
Callbacks 
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STRUCTURE 


Pure EGL hooks 


Direct replacement of application-facing EGL functions for resource management. 
Examples: 

eglGetPlatformDisplay() 

egiCreatePlatformWindowSurface() 


eglSwapBuffers() 
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STRUCTURE 


Derivatives of EGL functions 


Replace sub-parts of application-facing EGL functions. 


An example of these is queryString() which takes custom ‘name’ tokens to retrieve, 
for instance, sub-strings of the extensions string. 


The external platform manager can use each platform’s extension sub-string to 
compose the full string provided to applications. 
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STRUCTURE 


External object validation functions 


Functions such as eglGetDisplay(<native_dpy>), 
eglCreatelmage(EGL_WAYLAND BUFFER WL), or 
eglCreateStreamAttrib(EGL_WAYLAND EGLSTREAM WL) require helper functions 
to determine what external platform should handle those calls. 


Examples: 
isValidNativeDisplay(<native_dpy>) 


areStreamAttribsExternal(<attribs>) 
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STRUCTURE 


External to Internal object translation 


Non-externally implemented EGL functions will only understand internal EGL 
handles. 


The external API defines the getinternalHandle() function so the internal EGL handle 
of an EGL external resource can be retrieved and passed along to internal functions. 
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STRUCTURE 
Callbacks 


For those operations requiring non-application-facing EGL paths to work, EGL 
implementations are allowed to register callbacks with the external platform 
implementations. 


An example of these is setting EGL error codes to be queried by the application in 
case of failure in the external platform code. 


By calling into registerCallback(EXTERNAL_CALLBACK_SET_ERROR), an EGL 
implementation will let the external platform know the function to be called to set 
EGL error codes. 
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INTERACTIONS VVITH LIBEGL 


Discovery & Registration of EGL External platforms 


Discovery and registration of available EGL external platforms is lIbEGL's 
responsibility. 


A portable and fully configurable discovery mechanism is advisable (e.g. J SON 
loader). 


loadExternalPlatform(<major>, <minor>) function: 
Initial llbEGLS EGL external platform interaction 
Fills an EGL external platform exports table 


Lets libEGL select what API version to use 
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INTERACTIONS WITH LIBEGL 


EGL calls dispatch 


Application 


Application-facing EGL APIs 


Application-facing EGL APIs 


libDEGL EGL external 


platform 


EGL external platform APIs 


Driver internal APIs EGL external callbacks 


Driver internals 
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A PRACTICAL USE CASE: WAYLAND 


WAYLAND EXTERNAL PLATFORM 


NVIDIA’s Wayland platform is implemented on top of the EGLDevice and EGLStream 
families of extensions. 


The simplest application work flow looks like: 


eglGetDisplay() eglCreateWindowSurface() eglSwapBuffers() 


Let's see how the three functions above are implemented in the Wayland external 
platform and backed by EGLDevice and EGLStream operations. 


15 J NVIDIA. 


VVAYLAND EXTERNAL PLATFORM 
eglGetDisplay() 


Application 


eglGetDisplay(native_dpy) 


External::isValidNativeDisplay(native_dpy) 


External::getPlatformDisplay(WAYLAND, native_dpy) 
Wayland external 
libEGL eglQueryDevices() de d externa 


platformt 
eglGetPlatformDisplay(DEVICE, egl_ device) 


eglQueryDevices() 
eglGetPlatformDisplay(DEVICE, egl_ device) 


(*) For simplicity, wayland 
Driver internals communication with the server is 


left out of the picture 
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WAYLAND EXTERNAL PLATFORM 


eglCreateWindowSurface() 


Application 


eglCreateWindowSurface(dpy, native win) 


dpy->External::createPlatformWindowSurface(dpy, native win 


eglCreateStream(dpy->egl_dpy) 


libEGL eglGetStreamFileDescriptor(dpy->egl_dpy, egl_stream) Wayland external 


platform* 


eglCreateStreamProducerSurface(dpy->egl_dpy, egl_stream) 


eglCreateStream(egl_dpy) 
eglGetStreamFileDescriptor(egl_dpy, egl_stream) 
eglCreateStreamProducerSurface(egl_dpy, egl_stream) 


: (*) For simplicity, wayland 
Driver internals communication with the server is 


left out of the picture 
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VVAYLAND EXTERNAL PLATFORM 
eglSwapBuffers() 


Application 


eglSwapBuffers(dpy, surf) 


surf->External::swapBuffers(dpy, surf) 


Wayland external 


lbEGL ISwapBuff ->egl f->egl f 
eglSwapBuffers(dpy->egl_dpy, surf-segl prod surf) platform* 


eglSwapBuffers(egl_dpy, egl_prod_surf) 


: (*) For simplicity, wayland 
Driver internals communication with the server is 


left out of the picture 
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CONCLUSIONS 


CONCLUSIONS 


Introduced an EGL external platform API to decouple platform drivers from EGL 
drivers. 


Successfully added Wayland support as an external platform on top of the 
EGLDevice and EGLStream families of extensions. 


We will soon open source both the EGL External platform API and the Wayland 
implementation. 
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EXTRA: EGL EXTERNAL API 


struct ExternalEglExports 4 [...] 
registerCallback; 
createPlatformWindowSurface; 


isValidNativeDisplay; destroySurface; 
bindDisplays; swapBuffers; 
unbindDisplays, swapinterval; 
getPlatformDisplay; 

initialize; areStreamAttribsExternal; 
terminate, createStreamAttrib; 
chooseConfig; 

getConfigAttrib; queryString; 


queryNativeResource, 


[...] 


getInternalHandle; 
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